TODO: remember to bump this to 0.4.0, and we need to release @microsoft/durabletask-js first

also confirm whether @azure/functions 4.16.1 has the extension changes required,

addressed in f935bce

Bug (high): classic-vs-native detection by arity silently mis-runs native single-arg orchestrators.

handler.length === 1 treats any one-parameter function as classic. But a core-native orchestrator written as async function*(ctx) { yield ctx.callActivity(...) } — single param, ignoring input, a very common style — also has arity 1. It gets wrapped and invoked as classic(classicCtx), where classicCtx is { df, log, ... }, so ctx.callActivity is undefined.

Worse: because isGenerator() (line 257) checks for [Symbol.iterator], it returns false for the async generator the handler returns, so the wrapper returns the un-iterated generator and the engine completes the orchestration immediately with garbage output — the body never runs and nothing throws. (Note functions-grpc-support.spec.ts itself writes a native orchestrator as single-arg async (_ctx) => ....)

Suggest detecting by generator kind instead of arity, which matches the engine's actual async-iterator gate: handler.constructor.name === "GeneratorFunction" ⇒ classic (v3 sync generators); AsyncGeneratorFunction / async ⇒ native pass-through. Please also add a round-trip test that drives a native single-arg orchestrator through wrapOrchestrator → the real executor.

addressed in f935bce

addressed in 8f62a35 — refined: classic vs core-native orchestrators are now detected by generator/async kind instead of pure arity (async function*/async => core-native pass-through; sync function* => classic, wrapped; plain sync fn => arity fallback), and the wrapper drives both sync and async generators via yield*. Added end-to-end regression tests through the real core executor: single-arg native async-generator body actually runs and yields a task; classic single-arg sync generator still works; classic non-generator return value still works.

Break: createTimer returns a non-cancelable core Task, so the canonical durable-timeout pattern no longer works.

v3 createTimer returned a TimerTask with .cancel() / .isCanceled. The ubiquitous pattern

const timeout = context.df.createTimer(deadline);
const work = context.df.callActivity("DoWork");
const winner = yield context.df.Task.any([timeout, work]);
if (!timeout.isCompleted) timeout.cancel();

breaks two ways: core Task has no cancel() (→ TypeError, or a leaked timer that keeps the instance alive until it fires), and the result shape changed (isCompleted/isFaulted/result → isComplete/isFailed/getResult()), so timeout.isCompleted is always undefined. This is one of the most common DF patterns — consider surfacing a cancelable timer wrapper, or calling it out prominently in the migration notes.

addressed in f935bce

addressed in 8f62a35 — createTimer's return type is now TimerTask (core already returns a cancelable TimerTask via #293; only the type was hidden as Task). Added a test covering .cancel()/.isCanceled type visibility plus the Task.any(timer, work) then timer.cancel() timeout-race pattern.

Break: the classic context no longer extends InvocationContext.

v3's OrchestrationContext extends InvocationContext, so orchestrators could read context.invocationId, context.functionName, context.extraInputs, etc. This interface exposes only df + log methods, so any orchestrator touching those members won't compile/run. Same applies to ClassicEntityContext in entity-context.ts (just { df }). Worth documenting as a breaking change.

addressed in f935bce

addressed in 8f62a35 (doc-only) — CHANGELOG + README migration sections now record the breaking change: classic orchestration context exposes only df + replay-safe log helpers (no invocationId/functionName/extraInputs), and the classic entity context is just { df }. Added the rationale (reading InvocationContext members inside an orchestrator is replay-nondeterministic and was never recommended). No members restored.

Subtle break: v3's signature was createCheckStatusResponse(request: HttpRequest | undefined, instanceId) and fell back to the binding's baseUrl when request was undefined. This overload requires a defined request and will throw at request.url (in getInstanceStatusUrl) if called with undefined. Consider accepting HttpRequest | undefined to preserve the v3 contract.

addressed in f935bce

addressed in 8f62a35 — confirmed v3-faithful: createCheckStatusResponse(request: HttpRequest | undefined, instanceId) already accepts an undefined request and falls back to the durable-client binding's baseUrl to build the management payload; undefined-request test is in place. One nuance to flag: the compat layer reconstructs the status URL from baseUrl rather than rewriting the binding's managementUrls templates (behavior-equivalent for the status link on the consolidated path).

Subtle break: the return type is DurableOrchestrationStatus | undefined where v3 returned a non-optional DurableOrchestrationStatus, so existing callers doing (await getStatus(id)).runtimeStatus now get a TS error / possible runtime throw. Also GetStatusOptions.showHistory / showHistoryOutput are silently ignored and history is never populated (only showInput is honored). Worth documenting the reduced option set — and note startNew similarly drops v3's version option.

addressed in f935bce

addressed in 8f62a35 — getStatus now matches v3: returns a non-optional DurableOrchestrationStatus and throws when the instance is missing (verified against v3 DurableClient.getStatus, which throws on the extension's 404). showHistory populates history from core getOrchestrationHistory; startNew forwards the v3 version option to the core scheduler (scheduleNewOrchestration supports version). Honest boundaries (documented in JSDoc + CHANGELOG/README): history entries are core HistoryEvent shape, not the .NET extension's history shape (gRPC path bypasses the extension HTTP formatter); showHistoryOutput is accepted but can't strip payloads (core events always carry them); showInput maps to core fetchPayloads, so showInput:false also gates output/customStatus (v3 omitted only input).

further refined in 900064f — getStatus/startNew now implement all three v3 points (not just documented):

(a) not-found: verified v3 DurableClient.getStatus (src/durableClient/DurableClient.ts) — its case 404 throws and the return type is non-optional Promise. Replicated: returns non-optional status, throws a 'DurableClient error: No orchestration instance with ID ... was found.' Error when the instance is missing.

(b) showHistory/showHistoryOutput: showHistory populates history via core getOrchestrationHistory; showHistoryOutput toggles per-entry payloads (strips input/result when falsy, keeps them when true). v3 types history as Array (types/orchestration.d.ts), so entries are core HistoryEvent[]; the .NET extension's PascalCase HTTP history shape isn't reproduced because the gRPC path bypasses that formatter. showInput now gates only the top-level input (output/customStatus always returned, matching v3).

(c) version: startNew forwards options.version to core scheduleNewOrchestration (StartOrchestrationOptions.version).

Tests updated: not-found throw, showInput gates input only, showHistoryOutput strip vs keep, startNew version. build + lint + compat unit (81/81) green.

not-found message aligned with v3 in 0dcc47c — mirrors v3 DurableClient.getStatus's exact sentence: 'This usually means we could not find any data associated with the instanceId provided: .' Only v3's HTTP-404-specific first sentence is replaced (the gRPC path has no HTTP 404). Behavior is otherwise unchanged from 900064f: non-optional return + throw on not-found, showHistory/showHistoryOutput, showInput gates only input, startNew forwards version.

Nit: parseJson guards undefined but not "". JSON.parse("") throws, so a present-but-empty serialized payload would blow up getStatus / toDurableOrchestrationStatus. Normal flow yields undefined (absent StringValue wrapper) so this is low-risk, but cheap to harden: if (!value) return undefined;.

addressed in f935bce -- empty-string already guarded; now also tolerant of non-JSON serializedOutput

Break: several v3 top-level exports are missing, so import { ... } from "durable-functions" breaks for:

• DummyOrchestrationContext / DummyEntityContext — v3 testing utilities; users' existing unit tests won't compile.
• TaskFailedError (and v3's DurableError / AggregatedError) — needed for instanceof guards on caught orchestration errors; core throws its own TaskFailedError, which isn't re-exported here.
• ManagedIdentityTokenSource / TokenSource.

Relatedly, the app surface drops the v3 durable-client trigger helpers (df.app.client.http / timer / storageQueue / ...) and setExceptionPropertiesProvider. The replacement model (generic app.http + df.input.durableClient() + df.getClient(context)) is reasonable, but it changes client-function handler signatures and should be documented as a breaking migration.

addressed in f935bce

Minor (core): if versioning is enabled and a version mismatch resolves to abandon, _executeOrchestratorInternal calls the stub's no-op abandonTaskOrchestratorWorkItem and returns without setting a response — so this throws a generic "Orchestrator execution did not produce a response.". Unreachable via the Functions path today (the worker is constructed without versioning), but since this is a public, reusable entry point, consider distinguishing "abandoned" from a genuine failure, or documenting that abandon isn't supported on the single-work-item path.

addressed in f935bce

Nit: this looks like generated-proto churn — deserializeBinary / deserializeBinaryFromReader are merely reordered with no semantic change. Worth dropping from the diff to keep it focused (and confirm the proto codegen version isn't drifting).

addressed in f935bce

Nit: engines.node >= 22 is a notable consumer-facing floor (drops the Node 18/20 that v3 supported) — worth calling out in the README/changelog. It's also inconsistent with @types/node@^18 in devDependencies.

addressed in f935bce